5. IIIF Presentation API

Introduction to the Presentation API

Interlude

Interlude 2

1. Viewing experience

Digitised objects come in a wide variety of shapes and forms, with a wide variety of structure and conceptual model.

The Image API does not provide enough information to describe the range of viewing experiences we would need to be able present these digitised objects to a user.

The IIIF Presentation API allows us to provide more information about the features we want to present to the user and how we want to present them.

The IIIF Presentation API is not a metadata standard like:

The primary concern of the IIIF Presentation API is to provide enough information to a viewer, or a web page, for that viewer or web page to show the content with the right kind of user experience.

How does it do this?

2. IIIF Presentation API Model

2.1 Basic Resource Types

Primary Resource Types

Manifest

The overall description of the structure and properties of the digital representation of an object. It carries information needed for the viewer to present the digitized content to the user, such as a title and other descriptive information about the object or the intellectual work that it conveys. Each manifest describes how to present a single object such as a book, a photograph, or a statue.

Sequence

The order of the views of the object.

Canvas

A virtual container that represents a page or view and has content resources associated with it or with parts of it.

Think of a canvas as a little like a Powerpoint slide. A container onto which you can add content:

The canvas provides a frame of reference for the layout of the content. The concept of a canvas is borrowed from standards like PDF and HTML, or applications like Photoshop and Powerpoint, where the display starts from a blank canvas and images, text and other resources are "painted" on to it.

Canvases are the main carriers of content in IIIF, and in the IIIF model, content on canvases takes the form of annotations.

Range

An ordered list of canvases, and/or further ranges. Ranges allow canvases, or parts thereof, to be grouped together in some way. This could be for textual reasons, such as to distinguish books, chapters, verses, sections, non-content-bearing pages, the table of contents or similar. Equally, physical features might be important such as quires or gatherings, sections that have been added later and so forth.

2.2. Descriptive Properties

label

A human readable label, name or title for the resource.

metadata

A list of short descriptive entries, given as pairs of human readable label and value to be displayed to the user. An example pair of label and value might be a label of "Author" and a value of "Jehan Froissart".

description

A longer-form prose description of the object or resource that the property is attached to, intended to be conveyed to the user as a full text description, rather than a simple label and value.

thumbnail

A small image that depicts or pictorially represents the resource that the property is attached to, such as the title page, a significant image or rendering of a canvas with multiple content resources associated with it.

2.3. Rights and Licensing Properties

attribution

Text that MUST be shown when the resource it is associated with is displayed or used. For example, this could be used to present copyright or ownership statements, or simply an acknowledgement of the owning and/or publishing institution.

license

A link to an external resource that describes the license or rights statement under which the resource may be used.

logo

A small image that represents an individual or organization associated with the resource it is attached to. This could be the logo of the owning or hosting institution.

2.4. Technical Properties

viewingDirection

The direction that a sequence of canvases SHOULD be displayed to the user. Possible values are specified in the table below.

| Value | Description |
| ----- | ----------- |
| left-to-right | The object is displayed from left to right. The default if not specified. |
| right-to-left | The object is displayed from right to left. |
| top-to-bottom | The object is displayed from the top to the bottom. |
| bottom-to-top | The object is displayed from the bottom to the top. |
{: .api-table}

viewingHint

A hint to the client as to the most appropriate method of displaying the resource. This specification defines the values specified in the table below.

| Value | Description |
| ----- | ----------- |
| individuals | Valid on collection, manifest, sequence and range. When used as the viewingHint of a collection, the client should treat each of the manifests as distinct individual objects. For manifest, sequence and range, the canvases referenced are all distinct individual views, and SHOULD NOT be presented in a page-turning interface. Examples include a gallery of paintings, a set of views of a 3 dimensional object, or a set of the front sides of photographs in a collection. |
| paged | Valid on manifest, sequence and range. Canvases with this viewingHint represent pages in a bound volume, and SHOULD be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas represents the back of the object in the first canvas. |
| continuous | Valid on manifest, sequence and range. A canvas with this viewingHint is a partial view and an appropriate rendering might display either the canvases individually, or all of the canvases virtually stitched together in the display. Examples when this would be appropriate include long scrolls, rolls, or objects designed to be displayed adjacent to each other. If this viewingHint is present, then the resource MUST also have a viewingDirection which will determine the arrangement of the canvases. Note that this does not allow for both sides of a scroll to be included in the same manifest with this viewingHint. To accomplish that, the manifest should be "individuals" and have two ranges, one for each side, which are "continuous". |
| multi-part | Valid only for collections. Collections with this viewingHint consist of multiple manifests that each form part of a logical whole. Clients might render the collection as a table of contents, rather than with thumbnails. Examples include multi-volume books or a set of journal issues or other serials. |
| non-paged | Valid only for canvases. Canvases with this viewingHint MUST NOT be presented in a page turning interface, and MUST be skipped over when determining the page sequence. This viewing hint MUST be ignored if the current sequence or manifest does not have the 'paged' viewing hint. |
| top | Valid only for ranges. A Range with this viewingHint is the top-most node in a hierarchy of ranges that represents a structure to be rendered by the client to assist in navigation. For example, a table of contents within a paged object, major sections of a 3d object, the textual areas within a single scroll, and so forth. Other ranges that are descendants of the "top" range are the entries to be rendered in the navigation structure. There MAY be multiple ranges marked with this hint. If so, the client SHOULD display a choice of multiple structures to navigate through. |
| facing-pages | Valid only for canvases. Canvases with this viewingHint, in a sequence or manifest with the "paged" viewing hint, MUST be displayed by themselves, as they depict both parts of the opening. If all of the canvases are like this, then page turning is not possible, so simply use "individuals" instead. |

navDate

A date that the client can use for navigation purposes when presenting the resource to the user in a time-based user interface, such as a calendar or timeline.

2.5. Linking Properties

related

A link to an external resource intended to be displayed directly to the user. Examples might include a video or academic paper about the resource, a website, an HTML description, and so forth.

rendering

A link to an external resource intended for display or download by a human user. For example, a rendering of a manifest as a PDF or EPUB with the images and text of the book, or a slide deck with images of the museum object.

seeAlso

A link to a machine readable document that semantically describes the resource with the seeAlso property, such as an XML or RDF description. This document could be used for search and discovery or inferencing purposes, or just to provide a longer description of the resource.

startCanvas

This allows the client to begin with the first canvas that contains interesting content rather than requiring the user to skip past blank or empty canvases manually.

Sample National Library of Norway Manifest

https://api.nb.no/catalog/v1/iiif/ea3d85be891d3e04e68743c795930397/manifest

The Mahabharata Scroll:

https://librarylabs.ed.ac.uk/iiif/manifest/mahabharataFinal.json